@rollup/plugin-typescript

What is @rollup/plugin-typescript?

@rollup/plugin-typescript is a Rollup plugin that allows you to seamlessly integrate TypeScript into your Rollup build process. It compiles TypeScript files and includes them in your bundle, making it easier to work with TypeScript in a Rollup-based project.

What are @rollup/plugin-typescript's main functionalities?

Basic TypeScript Compilation

This feature allows you to compile TypeScript files into JavaScript. The code sample demonstrates a basic Rollup configuration that compiles a TypeScript file located at 'src/index.ts' and outputs a bundled JavaScript file at 'dist/bundle.js'.

const typescript = require('@rollup/plugin-typescript');

module.exports = {
  input: 'src/index.ts',
  output: {
    file: 'dist/bundle.js',
    format: 'cjs'
  },
  plugins: [
    typescript()
  ]
};

Custom TypeScript Compiler Options

This feature allows you to specify custom TypeScript compiler options by providing a path to a custom tsconfig.json file. The code sample shows how to use a custom TypeScript configuration file named 'tsconfig.custom.json'.

const typescript = require('@rollup/plugin-typescript');

module.exports = {
  input: 'src/index.ts',
  output: {
    file: 'dist/bundle.js',
    format: 'cjs'
  },
  plugins: [
    typescript({
      tsconfig: 'tsconfig.custom.json'
    })
  ]
};

Type Checking

This feature enables type checking during the build process. The code sample demonstrates how to enable type checking by setting the 'check' option to true.

const typescript = require('@rollup/plugin-typescript');

module.exports = {
  input: 'src/index.ts',
  output: {
    file: 'dist/bundle.js',
    format: 'cjs'
  },
  plugins: [
    typescript({
      check: true
    })
  ]
};

Other packages similar to @rollup/plugin-typescript

rollup-plugin-typescript2

rollup-plugin-typescript2 is another Rollup plugin for integrating TypeScript. It offers more advanced features like incremental builds and better error reporting compared to @rollup/plugin-typescript. However, it may have a steeper learning curve due to its additional configuration options.

ts-loader

ts-loader is a TypeScript loader for Webpack. While it is not a Rollup plugin, it serves a similar purpose in the Webpack ecosystem by allowing you to compile TypeScript files. It is highly configurable and integrates well with Webpack's ecosystem.

babel-plugin-transform-typescript

babel-plugin-transform-typescript is a Babel plugin that allows you to compile TypeScript using Babel. This can be useful if you are already using Babel for other transformations and want to keep your build process consistent. However, it does not perform type checking.

README

@rollup/plugin-typescript

🍣 A Rollup plugin for seamless integration between Rollup and Typescript.

Requirements

This plugin requires an LTS Node version (v8.0.0+) and Rollup v1.20.0+. Due to the use of tslib to inject helpers, this plugin requires at least TypeScript 2.1. See also here.

Install

Using npm:

npm install @rollup/plugin-typescript --save-dev

Note that both typescript and tslib are peer dependencies of this plugin that need to be installed separately.

Why?

See @rollup/plugin-babel.

Usage

Create a rollup.config.js configuration file and import the plugin:

// rollup.config.js
import typescript from '@rollup/plugin-typescript';

export default {
  input: 'src/index.ts',
  output: {
    dir: 'output',
    format: 'cjs'
  },
  plugins: [typescript()]
};

Then call rollup either via the CLI or the API.

Options

The plugin loads any compilerOptions from the tsconfig.json file by default. Passing options to the plugin directly overrides those options:

...
export default {
  input: './main.ts',
  plugins: [
      typescript({lib: ["es5", "es6", "dom"], target: "es5"})
  ]
}

The following options are unique to rollup-plugin-typescript:

exclude

Type: String | Array[...String]
Default: null

A minimatch pattern, or array of patterns, which specifies the files in the build the plugin should ignore. By default no files are ignored.

include

Type: String | Array[...String]
Default: null

A minimatch pattern, or array of patterns, which specifies the files in the build the plugin should operate on. By default all .ts and .tsx files are targeted.

tsconfig

Type: String | Boolean
Default: true

When set to false, ignores any options specified in the config file. If set to a string that corresponds to a file path, the specified file will be used as config file.

typescript

Type: import('typescript')
Default: peer dependency

Overrides the TypeScript module used for transpilation.

typescript({
  typescript: require('some-fork-of-typescript')
});

tslib

Type: String
Default: peer dependency

Overrides the injected TypeScript helpers with a custom version.

typescript({
  tslib: require.resolve('some-fork-of-tslib')
});

Typescript compiler options

Some of Typescript's CompilerOptions affect how Rollup builds files.

noEmitOnError

Type: Boolean
Default: true

If a type error is detected, the Rollup build is aborted when this option is set to true.

files, include, exclude

Type: Array[...String]
Default: []

Declaration files are automatically included if they are listed in the files field in your tsconfig.json file. Source files in these fields are ignored as Rollup's configuration is used instead.

Ignored options

These compiler options are ignored by Rollup:

• noEmitHelpers, importHelpers: The tslib helper module always must be used.
• noEmit, emitDeclarationOnly: Typescript needs to emit code for the plugin to work with.
• noResolve: Preventing Typescript from resolving code may break compilation

Importing CommonJS

Though it is not recommended, it is possible to configure this plugin to handle imports of CommonJS files from TypeScript. For this, you need to specify CommonJS as the module format and add rollup-plugin-commonjs to transpile the CommonJS output generated by TypeScript to ES Modules so that rollup can process it.

// rollup.config.js
import typescript from '@rollup/plugin-typescript';
import commonjs from '@rollup/plugin-commonjs';

export default {
  input: './main.ts',
  plugins: [
    typescript({ module: 'CommonJS' }),
    commonjs({ extensions: ['.js', '.ts'] }) // the ".ts" extension is required
  ]
};

Note that this will often result in less optimal output.

Preserving JSX output

Whenever choosing to preserve JSX output to be further consumed by another transform step via tsconfig compilerOptions by setting jsx: 'preserve' or overriding options, please bear in mind that, by itself, this plugin won't be able to preserve JSX output, usually failing with:

[!] Error: Unexpected token (Note that you need plugins to import files that are not JavaScript)
file.tsx (1:15)
1: export default <span>Foobar</span>
                  ^

To prevent that, make sure to use the acorn plugin, namely acorn-jsx, which will make Rollup's parser acorn handle JSX tokens. (See https://rollupjs.org/guide/en/#acorninjectplugins)

After adding acorn-jsx plugin, your Rollup config would look like the following, correctly preserving your JSX output.

import jsx from 'acorn-jsx';
import typescript from '@rollup/plugin-typescript';

export default {
  // … other options …
  acornInjectPlugins: [jsx()],
  plugins: [typescript({ jsx: 'preserve' })]
};

Faster compiling

Previous versions of this plugin used Typescript's transpileModule API, which is faster but does not perform typechecking and does not support cross-file features like const enums and emit-less types. If you want this behaviour, you can use @rollup/plugin-sucrase instead.

Meta

CONTRIBUTING

LICENSE (MIT)